From 6993105c84c12958fbb158eb0e3f9f5c37739577 Mon Sep 17 00:00:00 2001 From: Matthias Clasen Date: Sun, 15 Feb 2004 01:47:05 +0000 Subject: [PATCH] Document the tree DND API. Sun Feb 15 02:49:45 2004 Matthias Clasen * gtk/gtktreednd.c: * gtk/gtktreeview.c: Document the tree DND API. * gtk/gtktreeview.c (gtk_tree_view_unset_rows_drag_source): Call gtk_drag_source_unset(). --- ChangeLog | 8 ++ ChangeLog.pre-2-10 | 8 ++ ChangeLog.pre-2-4 | 8 ++ ChangeLog.pre-2-6 | 8 ++ ChangeLog.pre-2-8 | 8 ++ docs/reference/ChangeLog | 4 + docs/reference/gtk/tmpl/gtktreednd.sgml | 107 ++++++++++++++++++++++-- gtk/gtktreednd.c | 2 +- gtk/gtktreeview.c | 62 ++++++++++++++ 9 files changed, 205 insertions(+), 10 deletions(-) diff --git a/ChangeLog b/ChangeLog index b165aad97d..ed09d8a7f2 100644 --- a/ChangeLog +++ b/ChangeLog @@ -1,3 +1,11 @@ +Sun Feb 15 02:49:45 2004 Matthias Clasen + + * gtk/gtktreednd.c: + * gtk/gtktreeview.c: Document the tree DND API. + + * gtk/gtktreeview.c (gtk_tree_view_unset_rows_drag_source): + Call gtk_drag_source_unset(). + Sun Feb 15 00:49:59 2004 Matthias Clasen * gtk/gtkcellrendererpixbuf.c (gtk_cell_renderer_pixbuf_class_init): diff --git a/ChangeLog.pre-2-10 b/ChangeLog.pre-2-10 index b165aad97d..ed09d8a7f2 100644 --- a/ChangeLog.pre-2-10 +++ b/ChangeLog.pre-2-10 @@ -1,3 +1,11 @@ +Sun Feb 15 02:49:45 2004 Matthias Clasen + + * gtk/gtktreednd.c: + * gtk/gtktreeview.c: Document the tree DND API. + + * gtk/gtktreeview.c (gtk_tree_view_unset_rows_drag_source): + Call gtk_drag_source_unset(). + Sun Feb 15 00:49:59 2004 Matthias Clasen * gtk/gtkcellrendererpixbuf.c (gtk_cell_renderer_pixbuf_class_init): diff --git a/ChangeLog.pre-2-4 b/ChangeLog.pre-2-4 index b165aad97d..ed09d8a7f2 100644 --- a/ChangeLog.pre-2-4 +++ b/ChangeLog.pre-2-4 @@ -1,3 +1,11 @@ +Sun Feb 15 02:49:45 2004 Matthias Clasen + + * gtk/gtktreednd.c: + * gtk/gtktreeview.c: Document the tree DND API. + + * gtk/gtktreeview.c (gtk_tree_view_unset_rows_drag_source): + Call gtk_drag_source_unset(). + Sun Feb 15 00:49:59 2004 Matthias Clasen * gtk/gtkcellrendererpixbuf.c (gtk_cell_renderer_pixbuf_class_init): diff --git a/ChangeLog.pre-2-6 b/ChangeLog.pre-2-6 index b165aad97d..ed09d8a7f2 100644 --- a/ChangeLog.pre-2-6 +++ b/ChangeLog.pre-2-6 @@ -1,3 +1,11 @@ +Sun Feb 15 02:49:45 2004 Matthias Clasen + + * gtk/gtktreednd.c: + * gtk/gtktreeview.c: Document the tree DND API. + + * gtk/gtktreeview.c (gtk_tree_view_unset_rows_drag_source): + Call gtk_drag_source_unset(). + Sun Feb 15 00:49:59 2004 Matthias Clasen * gtk/gtkcellrendererpixbuf.c (gtk_cell_renderer_pixbuf_class_init): diff --git a/ChangeLog.pre-2-8 b/ChangeLog.pre-2-8 index b165aad97d..ed09d8a7f2 100644 --- a/ChangeLog.pre-2-8 +++ b/ChangeLog.pre-2-8 @@ -1,3 +1,11 @@ +Sun Feb 15 02:49:45 2004 Matthias Clasen + + * gtk/gtktreednd.c: + * gtk/gtktreeview.c: Document the tree DND API. + + * gtk/gtktreeview.c (gtk_tree_view_unset_rows_drag_source): + Call gtk_drag_source_unset(). + Sun Feb 15 00:49:59 2004 Matthias Clasen * gtk/gtkcellrendererpixbuf.c (gtk_cell_renderer_pixbuf_class_init): diff --git a/docs/reference/ChangeLog b/docs/reference/ChangeLog index c1eb4c13c1..59113ab26b 100644 --- a/docs/reference/ChangeLog +++ b/docs/reference/ChangeLog @@ -1,3 +1,7 @@ +Sun Feb 15 02:46:53 2004 Matthias Clasen + + * gtk/tmpl/gtktreednd.sgml: Add docs. + Sat Feb 14 03:09:49 2004 Matthias Clasen * gtk/gtk-sections.txt: Remove duplicated section for diff --git a/docs/reference/gtk/tmpl/gtktreednd.sgml b/docs/reference/gtk/tmpl/gtktreednd.sgml index 9414655b6b..9c244f5312 100644 --- a/docs/reference/gtk/tmpl/gtktreednd.sgml +++ b/docs/reference/gtk/tmpl/gtktreednd.sgml @@ -2,27 +2,82 @@ GtkTreeView drag-and-drop - +Interfaces for drag-and-drop support in GtkTreeView +GTK+ supports Drag-and-Drop in tree views with a high-level and a low-level +API. + + +The low-level API consists of the GTK+ DND API, augmented by some treeview +utility functions: gtk_tree_view_set_drag_dest_row(), +gtk_tree_view_get_drag_dest_row(), gtk_tree_view_get_dest_row_at_pos(), +gtk_tree_view_create_row_drag_icon(), gtk_tree_set_row_drag_data() and +gtk_tree_get_row_drag_data(). This API leaves a lot of flexibility, but +nothing is done automatically, and implementing advanced features like +hover-to-open-rows or autoscrolling on top of this API is a lot of work. + + +On the other hand, if you write to the high-level API, then all the +bookkeeping of rows is done for you, as well as things like hover-to-open +and auto-scroll, but your models have to implement the +#GtkTreeDragSource and #GtkTreeDragDest interfaces. + + + + + + - + + + + +@g_iface: +@row_draggable: +@drag_data_get: +@drag_data_delete: - + +@drag_source: +@path: +@Returns: - + + + + + + +@drag_source: +@path: +@selection_data: +@Returns: + + + + + + + +@drag_source: +@path: +@Returns: + + + @@ -37,13 +92,47 @@ GtkTreeView drag-and-drop @drag_data_received: @row_drop_possible: - + -@g_iface: -@row_draggable: -@drag_data_get: -@drag_data_delete: +@drag_dest: +@dest: +@selection_data: +@Returns: + + + + + + + +@drag_dest: +@dest_path: +@selection_data: +@Returns: + + + + + + + +@selection_data: +@tree_model: +@path: +@Returns: + + + + + + + +@selection_data: +@tree_model: +@path: +@Returns: + diff --git a/gtk/gtktreednd.c b/gtk/gtktreednd.c index 0af3d00267..e99bc617b4 100644 --- a/gtk/gtktreednd.c +++ b/gtk/gtktreednd.c @@ -186,7 +186,7 @@ gtk_tree_drag_dest_drag_data_received (GtkTreeDragDest *drag_dest, /** - * gtk_tree_drag_dest_drop_possible: + * gtk_tree_drag_dest_row_drop_possible: * @drag_dest: a #GtkTreeDragDest * @dest_path: destination row * @selection_data: the data being dragged diff --git a/gtk/gtktreeview.c b/gtk/gtktreeview.c index 240fa36caa..18f6a1c2c3 100644 --- a/gtk/gtktreeview.c +++ b/gtk/gtktreeview.c @@ -10914,6 +10914,17 @@ unset_reorderable (GtkTreeView *tree_view) } } +/** + * gtk_tree_view_enable_model_drag_source: + * @tree_view: a #GtkTreeView + * @start_button_mask: Mask of allowed buttons to start drag + * @targets: the table of targets that the drag will support + * @n_targets: the number of items in @targets + * @actions: the bitmask of possible actions for a drag from this + * widget + * + * Turns @tree_view into a drag source for automatic DND. + **/ void gtk_tree_view_enable_model_drag_source (GtkTreeView *tree_view, GdkModifierType start_button_mask, @@ -10943,6 +10954,16 @@ gtk_tree_view_enable_model_drag_source (GtkTreeView *tree_view, unset_reorderable (tree_view); } +/** + * gtk_tree_view_enable_model_drag_dest: + * @tree_view: a #GtkTreeView + * @targets: the table of targets that the drag will support + * @n_targets: the number of items in @targets + * @actions: the bitmask of possible actions for a drag from this + * widget + * + * Turns @tree_view into a drop destination for automatic DND. + **/ void gtk_tree_view_enable_model_drag_dest (GtkTreeView *tree_view, const GtkTargetEntry *targets, @@ -10970,6 +10991,12 @@ gtk_tree_view_enable_model_drag_dest (GtkTreeView *tree_view, unset_reorderable (tree_view); } +/** + * gtk_tree_view_unset_rows_drag_source: + * @tree_view: a #GtkTreeView + * + * Undoes the effect of gtk_tree_view_enable_model_drag_source(). + **/ void gtk_tree_view_unset_rows_drag_source (GtkTreeView *tree_view) { @@ -10983,6 +11010,7 @@ gtk_tree_view_unset_rows_drag_source (GtkTreeView *tree_view) { if (di->source_set) { + gtk_drag_source_unset (GTK_WIDGET (tree_view)); clear_source_info (di); di->source_set = FALSE; } @@ -10994,6 +11022,12 @@ gtk_tree_view_unset_rows_drag_source (GtkTreeView *tree_view) unset_reorderable (tree_view); } +/** + * gtk_tree_view_unset_rows_drag_dest: + * @tree_view: a #GtkTreeView + * + * Undoes the effect of gtk_tree_view_enable_model_drag_dest(). + **/ void gtk_tree_view_unset_rows_drag_dest (GtkTreeView *tree_view) { @@ -11019,6 +11053,14 @@ gtk_tree_view_unset_rows_drag_dest (GtkTreeView *tree_view) unset_reorderable (tree_view); } +/** + * gtk_tree_view_set_drag_dest_row: + * @tree_view: a #GtkTreeView + * @path: The path of the row to highlight, or %NULL. + * @pos: Specifies whether to drop before, after or into the row + * + * Sets the row that is highlighted for feedback. + **/ void gtk_tree_view_set_drag_dest_row (GtkTreeView *tree_view, GtkTreePath *path, @@ -11089,6 +11131,14 @@ gtk_tree_view_set_drag_dest_row (GtkTreeView *tree_view, } } +/** + * gtk_tree_view_get_drag_dest_row: + * @tree_view: a #GtkTreeView + * @path: Return location for the path of the highlighted row, or %NULL. + * @pos: Return location for the drop position, or %NULL + * + * Gets information about the row that is highlighted for feedback. + **/ void gtk_tree_view_get_drag_dest_row (GtkTreeView *tree_view, GtkTreePath **path, @@ -11113,6 +11163,18 @@ gtk_tree_view_get_drag_dest_row (GtkTreeView *tree_view, *pos = tree_view->priv->drag_dest_pos; } +/** + * gtk_tree_view_get_dest_row_at_pos: + * @tree_view: a #GtkTreeView + * @drag_x: the position to determine the destination row for + * @drag_y: the position to determine the destination row for + * @path: Return location for the path of the highlighted row, or %NULL. + * @pos: Return location for the drop position, or %NULL + * + * Determines the destination row for a given position. + * + * Return value: whether there is a row at the given postiion, + **/ gboolean gtk_tree_view_get_dest_row_at_pos (GtkTreeView *tree_view, gint drag_x, -- 2.30.2